Skills registry: pull, bind and qualify attested skills - #1623

Replaces #1592 with one squashed commit, so the secret scan, which reads the PR's history, no longer sees two test values from its earlier commits. The content is #1592's final tree (e8a161b).

Review history:

• Review of Skills registry: signed entries, provenance in the workflow, qualify before any run #1592 at 4c584fd: Skills registry: signed entries, provenance in the workflow, qualify before any run #1592 (comment)
• How it was addressed: Skills registry: signed entries, provenance in the workflow, qualify before any run #1592 (comment)

Since that reply: sigstore (the registry and dev extras) is limited to Python 3.11+, because on 3.10 it resolves dnspython 2.8.0 (GHSA-45c3-73f7-pv4m). Two test values that looked like credentials were replaced with plain text.

Stage 1 of the verified-skills registry. The design is in packages/flow/docs/design/SKILLS_REGISTRY.md, and it builds on openadapt pull (#1173).

A skill pulled from the registry runs only after it is qualified on the user's own instance: a registry certification is evidence about our test copy, never about theirs. Who published the index is established keylessly, with GitHub artifact attestations, as for our other releases.

Who published it: keyless attestation

• The release. .github/workflows/release-registry.yml runs in stages:

  • A manual dispatch from main tags registry-<suffix> with the release App.
  • On the tag push, an unprivileged check job runs the bundle checks.
  • The attest job then runs in release-identity, and it is the only job with id-token: write. It builds reproducible archives, stamps the index (issued_at, a 30-day expires_at, and serial) and attests index.json and every archive with actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6. It checks its own attestation with the pull verifier, using only hash-pinned wheels (registry/verify-requirements.txt).
  • publish releases the archives, index.json and index.sigstore.json. It opens a PR with the index and its attestation, adding both by name.

• The check. pull verifies index.sigstore.json with the sigstore package (the new registry extra, so the base install doesn't grow). The check is offline against openadapt_flow/registry_trusted_root.json, for a pinned identity:

  • issuer https://token.actions.githubusercontent.com;
  • SAN https://github.com/OpenAdaptAI/OpenAdapt/.github/workflows/release-registry.yml@refs/tags/registry-*;
  • source repository https://github.com/OpenAdaptAI/OpenAdapt.

  The statement must name the sha256 of the exact index that was read, and of any archive pulled.

• Refreshing trust. pull --refresh-trust fetches the current Sigstore trusted root through Sigstore's TUF repository into $OPENADAPT_HOME. After that, verification uses the refreshed root.

• Rollback and freeze. The attested index carries issued_at, expires_at and serial. pull refuses an expired index, one issued in the future, and a serial lower than the highest it has seen from that address ($OPENADAPT_HOME/registry-state.json). An entry dropped from the index changes its digest.

• Local only. For an index being authored on the local disk:

  • --allow-unsigned takes one with no attestation;
  • --allow-test-key takes one attested by the local test signer (registry_attest.sign_test).

  Both flags are refused for a remote index, and plain http is refused.

• Removed:

  • the signing seed (REGISTRY_SIGNING_SEED) and the registry-signing environment;
  • the Ed25519 entry and index signatures;
  • registry_keys.json;
  • the custom registry_index_sha256 Rekor anchor (the attestation is already in Rekor).

Pull, bind, qualify, run

• Provenance in the workflow. pull stores Workflow.registry: the entry id, version, index, the entry's sha256, who attested it and the published digest. The content digest covers it. pull also records the program's steps outside the bundle ($OPENADAPT_HOME/pulled.json), so a bundle with its provenance stripped is still refused. It writes skill.lock.json and expires any certification the bundle carries.
• skill bind records the user's values for the contract's declared variables: URLs, environment variable names, local paths and local commands. Each is checked against its kind, and a credential is only ever a variable name. The binding file is written mode 600.
• skill qualify runs the qualification cases in place against the bound instance. It uses the private tier's full check when OPENADAPT_REGISTRY_TOKEN is set, else the bundled minimal one.
  • A shipped contract never runs code it names and never reads the environment. Before expansion, its reset command and URL, its addresses, credential names and paths must each be a declared ${VAR}. Hooks and plugins are refused, and expansion uses the binding alone.
  • The user's own --verify counts only for a skill that ships none, or with --replace-contract.
• The refusal. run, replay, emit-skill and emit-mcp refuse a pulled skill without a current certification on a named instance, recorded by skill qualify for this digest. run and replay check the deployment's app address. An emitted web MCP server checks every call's URL against the qualified instance.
• The private tier. full_contract takes exactly a url and a sha256. The token is sent only over https to a host in registry.PRIVATE_TIER_HOSTS, checked before it is sent. The body is size-capped and kept beside the bundle, never in it.
• Archives are https-only, or inside a local index's directory. Member sizes are checked before any read, the total and the count are capped, and every member must be in the entry or be the license NOTICE.
• Public bundles hold only allowlisted files. Screen templates need the entry's screens.data: synthetic attestation. Versions order as semver.

Not in this PR

• Seed entries. OpenEMR; Medplum (needs focus_on: check who has the focus after a key that changes nothing visible #1579 and feat: arm a create-new form's save by the form the run typed into #1581); openIMIS (needs a Rosetta host); Odoo 18 Community (its fixture is written on Second installation on Medplum and openIMIS: Phase A by hand (evidence, harness, fixtures) #1548); and Dolibarr. These need fixture leases and blind fault suites.
• The first registry release. Until it runs, main has no index.sigstore.json, so pull from the default index is refused. A remote index has no bypass. This needs no key, only a dispatch of the reviewed workflow after this merges.

Tests

• tests/test_skills_registry.py and tests/test_registry.py: the index, pull, bind, qualify and the refusal; the attestation (pull and record the attester; no attestation; the test signer needs the flag; a changed index, signature or subject); and archives.

• tests/test_skills_registry_review.py: one or more tests per supply-chain review item, plus the Sigstore path.

• The real Sigstore path. The fixture is an attestation GitHub made for the OpenAdapt Desktop 0.24.1 SHA256SUMS release asset (desktop-release.yml). It is verified offline with the pinned trusted root and must name that file's sha256. These are refused:

  • the same bundle checked against the pinned registry identity (another workflow);
  • a changed statement;
  • a trusted root without Fulcio's keys.

  These tests skip when sigstore isn't installed, and run in CI, because dev includes it.

Run locally at 4c584fd: 142 passed with sigstore installed. Without it, 50 passed and the 4 real-path tests skipped. The workflow-policy, packaging and capabilities tests pass, and ruff, ruff format, mypy and actionlint are clean.

🤖 Generated with Claude Code